home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / comm / yarn_053.zip / YARN.DOC < prev    next >
Text File  |  1993-12-30  |  20KB  |  651 lines
  1.  
  2.  
  3. YARN(1)                                                                 YARN(1)
  4.  
  5.  
  6.  
  7.      Yarn - offline news storage and reading system
  8.  
  9.      Copyright (c) 1993 Chin Huang
  10.  
  11.      Permission to copy and distribute this material for any purpose and
  12.      without fee is hereby granted, provided that the above copyright notice
  13.      and this permission notice appear in all copies.  CHIN HUANG MAKES NO
  14.      REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL FOR ANY
  15.      PURPOSE.  IT IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
  16.      WARRANTIES.
  17.  
  18.                                  INTRODUCTION
  19.  
  20.      Yarn is a suite of programs for your personal computer, used to store and
  21.      read USENET news downloaded from a USENET host.
  22.  
  23. FEATURES
  24.  
  25.      -  An import program inserts USENET articles into a "news base" from
  26.         Simple Offline USENET Packet (SOUP) format.
  27.  
  28.      -  For each newsgroup, you specify the number of days to keep articles,
  29.         after which, an expire program deletes them.  However, articles
  30.         containing an Expires: header are deleted on the date specified in the
  31.         header.
  32.  
  33.      -  The news base stores only one copy of a cross-posted article.  The news
  34.         base implementation stores multiple articles per file.
  35.  
  36.      -  The Yarn news reader presents articles in threads arranged by Message-
  37.         ID and References.  The reader program generates SOUP reply packets.
  38.  
  39.      -  Multiple users are supported by storing separate configuration files
  40.         for each user.
  41.  
  42. SYSTEM REQUIREMENTS
  43.  
  44.      -  MS-DOS 3.0 or higher
  45.  
  46.      -  a lot of hard disk storage, depending on how much news you want to
  47.         keep.  For example, the author subscribes to 120 newsgroups including
  48.         some binaries and sources groups, keeping most articles for 7 days.
  49.         The amount of disk space used is 40 megabytes.
  50.  
  51.                                  INSTALLATION
  52.  
  53. SET UP DIRECTORIES AND FILES
  54.  
  55.      -  Create a directory named \YARN and unpack the files from the Yarn
  56.         package into this directory.  Choose a disk drive with a lot of free
  57.         space because the news base will be stored here.  Set the YARN
  58.         environment variable to the \YARN directory.  For example:
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                                  Version 0.53                                 1
  65.  
  66.  
  67.  
  68. YARN(1)                                                                 YARN(1)
  69.  
  70.  
  71.              MKDIR C:\YARN
  72.              SET YARN=C:\YARN
  73.  
  74.  
  75.      -  Create a directory in which Yarn will store your user information.  Set
  76.         the HOME environment variable to this directory.  This will be called
  77.         the <home> directory.  For example:
  78.  
  79.              MKDIR C:\JIM
  80.              SET HOME=C:\JIM
  81.  
  82.  
  83.      -  Create the directory <home>\YARN and copy the file \YARN\CONFIG to this
  84.         directory.  For example:
  85.  
  86.              MKDIR C:\JIM\YARN
  87.              COPY \YARN\CONFIG C:\JIM\YARN\CONFIG
  88.  
  89.  
  90.      -  Set the environment variable TZ to your time zone.  The format of the
  91.         TZ string is
  92.  
  93.              zzz[+/-]h[h][ddd]
  94.  
  95.  
  96.         zzz is a three character field representing the name of the time zone.
  97.  
  98.         [+/-]h[h] is an optionally signed number representing the local time
  99.         zone's difference from Greenwich Mean Time (GMT) in hours.
  100.  
  101.         ddd is an optional three character field that represents the name of
  102.         the local time zone's daylight saving time.
  103.  
  104.         If no TZ environment variable is set, a default TZ=EST5EDT is assumed.
  105.  
  106.      Put the above SET commands in your AUTOEXEC.BAT file to ensure the
  107.      environment settings persist after the next time you reboot your system.
  108.      (If you are installing Yarn for OS/2, put the SET commands in your
  109.      CONFIG.SYS file instead.)
  110.  
  111. EDIT THE CONFIGURATION FILE
  112.  
  113.      Edit the configuration file <home>\YARN\CONFIG to suit the user.  The
  114.      following entries in the configuration file must be set.
  115.  
  116.      user      Set this to your login name on the host from which you download
  117.                and upload USENET news.
  118.  
  119.      host      Set this to the full domain name of your host.
  120.  
  121.      name      Set this to your full name.  This is the name that appears in
  122.                parentheses on the From: header in messages you send.
  123.  
  124.      editor    Set the name of the editor program to run when you send
  125.                messages.  The program must be in your PATH.
  126.  
  127.  
  128.  
  129.                                  Version 0.53                                 2
  130.  
  131.  
  132.  
  133. YARN(1)                                                                 YARN(1)
  134.  
  135.  
  136.      reply     Specify the full path of the SOUP reply packet file where your
  137.                outgoing messages are stored.  If the reply packet file does not
  138.                exist, it is created when you post an article or send a mail
  139.                message from the reader program.  When you exit the reader
  140.                program, the reply packet is ready to upload to your host.
  141.  
  142. SET UP MAIL ALIASES
  143.  
  144.      A mail alias is a word representing one or more mail addresses.  If a mail
  145.      alias appears in a To:, Cc:, or Bcc: header, it is replaced with the
  146.      corresponding address list when the message is sent.
  147.  
  148.      Create a file named <home>\YARN\ALIASES.  A mail alias is defined in the
  149.      file with the statement
  150.  
  151.           <name>=<addresses>
  152.  
  153.      where <name> is the name of the alias and <addresses> is a list of one or
  154.      more addresses.
  155.  
  156.      You can specify an alternate aliases file by using the statement
  157.  
  158.           aliases=<file>
  159.  
  160.      in the configuration file, where <file> is the full path of the aliases
  161.      file.
  162.  
  163. SET UP OTHER USERS
  164.  
  165.      To define another user, create a home directory for the user and set up
  166.      the <home>\YARN\CONFIG file as described above.  To run Yarn as that user,
  167.      set the HOME environment variable to the user's home directory.
  168.  
  169. ENVIRONMENT
  170.  
  171.      These enviroment variables modify the behaviour of Yarn if they are set.
  172.  
  173.      EDITOR    Specifies the external editor program, overriding the editor
  174.                specified in the configuration file.
  175.  
  176.      YARNRC    This is the path of an alternate configuration file to read
  177.                instead of the default one.
  178.  
  179. CREATE LIST OF ACTIVE NEWSGROUPS
  180.  
  181.      You must inform Yarn of every newsgroup you will be importing by running
  182.      the command
  183.  
  184.           newgroup <name> <keepDays>
  185.  
  186.      where <name> is the newsgroup name and <keepDays> is the number of days
  187.      that articles in the newsgroup will be kept before the expire program
  188.      deletes them.  If you later want to change the number of keep days, run
  189.      this command again, specifying the new keep days value.
  190.  
  191.  
  192.  
  193.  
  194.                                  Version 0.53                                 3
  195.  
  196.  
  197.  
  198. YARN(1)                                                                 YARN(1)
  199.  
  200.  
  201.      Instead of naming a newsgroup on the command line, you can specify a text
  202.      file containing a list of newsgroup names.  Every newsgroup listed in the
  203.      file is assigned the keep days value.
  204.  
  205.           newgroup @<file> <keepDays>
  206.  
  207.  
  208. REMOVE NEWSGROUP FROM ACTIVE LIST
  209.  
  210.      To remove a newsgroup from the active newsgroup list, run the command
  211.  
  212.           rmgroup <name>
  213.  
  214.      where <name> is the newsgroup name.
  215.  
  216.                                    OPERATION
  217.  
  218. IMPORT NEWS AND MAIL
  219.  
  220.      To import messages from SOUP format, run
  221.  
  222.           import <file>
  223.  
  224.      where <file> is the path of the SOUP file.  The import program takes these
  225.      options.
  226.  
  227.      -n        Do not delete the packet file.
  228.  
  229.      -q        Operate in quiet mode.  Do not list imported article numbers.
  230.  
  231.      -r        Import rnews batches instead of SOUP files.
  232.  
  233.      If the import program finds a newsgroup in the packet that is not in the
  234.      active newsgroup list, it adds the newsgroup to the active list.  The keep
  235.      days for the added newsgroup is specified by the "keep" setting in the
  236.      configuration file.  For example, if the configuration file contains the
  237.      line
  238.  
  239.           keep=7
  240.  
  241.      then articles are kept in the newsgroup for 7 days.
  242.  
  243. EXPIRE NEWS
  244.  
  245.      Periodically run the expire program to delete old articles from the news
  246.      base.  The program accepts these options:
  247.  
  248.      -d<n>     Assume it is <n> days in the future.  Use this option to expire
  249.                articles before they normally would have been expired.
  250.  
  251.      -n        Do not actually delete any articles.  Used for testing.
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.                                  Version 0.53                                 4
  260.  
  261.  
  262.  
  263. YARN(1)                                                                 YARN(1)
  264.  
  265.  
  266. READ NEWS
  267.  
  268.      Run the yarn program to read news and mail.  The reader program operates
  269.      in several modes -- the newsgroup selection level, the article selection
  270.      level, and the article reading level.
  271.  
  272.      In the newsgroup selection level, yarn displays a window listing the
  273.      newsgroups you are subscribed to along with the number of unread articles
  274.      in each newsgroup.  You can subscribe, unsubscribe or rearrange the order
  275.      of newsgroups in this list.  Press the [Ins] key to subscribe to a
  276.      newsgroup.  This brings up a list of unsubscribed newsgroups.  To make a
  277.      selection, use the arrow keys to move the highlight to the newsgroup, and
  278.      then press the [Enter] key.  The selected newsgroup is inserted into the
  279.      subscribed newsgroup list.  Press the [Del] key to unsubscribe from the
  280.      highlighted newsgroup.  To move a newsgroup in the list, press the [Del]
  281.      key to remove it, position the highlight to the desired location, then
  282.      press the [Ins] key and reinsert the newsgroup.
  283.  
  284.      By selecting a newsgroup, you go to the article selection level, where
  285.      yarn presents a list of the subjects of each article.  You can select an
  286.      article to read from this list, taking you to the article reading level.
  287.  
  288. NEWSGROUP SELECTION LEVEL
  289.  
  290.      These commands are available in the newsgroup selection level.
  291.  
  292.      Down Arrow
  293.           Move to the next newsgroup.
  294.  
  295.      Up Arrow
  296.           Move to the previous newsgroup.
  297.  
  298.      Tab, Alt-N
  299.           Move to the next newsgroup that contains unread articles.
  300.  
  301.      Shift-Tab, Alt-P
  302.           Move to the previous newsgroup that contains unread articles.
  303.  
  304.      Space
  305.           Go to the article selection level, listing only unread articles.
  306.  
  307.      Enter
  308.           Go to the article selection level, listing all articles.
  309.  
  310.      Ins, Alt-S
  311.           Subscribe to a newsgroup and insert the newsgroup at the current
  312.           position.
  313.  
  314.      Del, Alt-U
  315.           Unsubscribe from the highlighted newsgroup.
  316.  
  317.      Alt-A
  318.           Post an article to the highlighted newsgroup.
  319.  
  320.  
  321.  
  322.  
  323.  
  324.                                  Version 0.53                                 5
  325.  
  326.  
  327.  
  328. YARN(1)                                                                 YARN(1)
  329.  
  330.  
  331.      !    Run command shell.  Type "exit" to return to Yarn.
  332.  
  333.      Esc  Exit program
  334.  
  335. ARTICLE SELECTION LEVEL
  336.  
  337.      These commands are available in the article selection level.
  338.  
  339.      Down Arrow
  340.           Move to the next article.
  341.  
  342.      Up Arrow
  343.           Move to the previous article.
  344.  
  345.      Tab  Move to the first article of the next thread.
  346.  
  347.      Shift-Tab
  348.           Move backwards to the previous article beginning a thread.
  349.  
  350.      Space, Enter
  351.           Read the article.
  352.  
  353.      Del, Alt-N
  354.           Mark the article as read and go to the next unread article.
  355.  
  356.      Ins  Mark the article as unread.
  357.  
  358.      Alt-O
  359.           Save the current article through to the last article in the thread to
  360.           a folder.
  361.  
  362.      Alt-S
  363.           Save the current article through to the last article in the thread to
  364.           a file.  If the file already exists, the articles are appended to the
  365.           file.  The program prompts for a file name.  If you don't give a full
  366.           path name, the file is stored in the directory <home>/News.
  367.  
  368.      Alt-W
  369.           Same at Alt-S, except omit the article headers.
  370.  
  371.      Alt-K
  372.           Mark the current article through to the last article in the thread as
  373.           read.
  374.  
  375.      Alt-C
  376.           Mark all articles in the newsgroup as read.
  377.  
  378.      Alt-A
  379.           Post an article to the newsgroup.
  380.  
  381.      !    Run command shell.  Type "exit" to return to Yarn.
  382.  
  383.      Esc  Return to the newsgroup selection level.
  384.  
  385.  
  386.  
  387.  
  388.  
  389.                                  Version 0.53                                 6
  390.  
  391.  
  392.  
  393. YARN(1)                                                                 YARN(1)
  394.  
  395.  
  396. ARTICLE READING LEVEL
  397.  
  398.      These commands are available in the article reading level.
  399.  
  400.      Down Arrow
  401.           Scroll one line down.
  402.  
  403.      Up Arrow
  404.           Scroll one line up.
  405.  
  406.      PgDn, Space
  407.           Show next page.
  408.  
  409.      PgUp Show previous page.
  410.  
  411.      n    Mark the article as read and show the next unread article.
  412.  
  413.      N    Show next article.
  414.  
  415.      p    Show previous unread article.
  416.  
  417.      P    Show previous article.
  418.  
  419.      a, Alt-A
  420.           Post an article to the newsgroup.
  421.  
  422.      f    Post a followup article.
  423.  
  424.      F    Post a followup article, quoting the original article.
  425.  
  426.      r    Mail a reply to the author of the article.
  427.  
  428.      R    Mail a reply, quoting the original article.
  429.  
  430.      o    Save the article to a folder.
  431.  
  432.      s    Save the article to a file.  If the file already exists, the article
  433.           is appended to the file.  The program prompts for a file name.  If
  434.           you don't give a full path name, the file is stored in the directory
  435.           <home>/News.
  436.  
  437.      w    Same as s except omit article headers.
  438.  
  439.      x    ROT13 decrypt the article.
  440.  
  441.      j, Del
  442.           Mark the article as read.
  443.  
  444.      m, Ins
  445.           Mark the article as unread.
  446.  
  447.      k, Alt-K
  448.           Mark this article and the rest of the articles in the thread as read.
  449.  
  450.  
  451.  
  452.  
  453.  
  454.                                  Version 0.53                                 7
  455.  
  456.  
  457.  
  458. YARN(1)                                                                 YARN(1)
  459.  
  460.  
  461.      Alt-C
  462.           Mark all the articles in the newsgroup as read.
  463.  
  464.      v    Toggle verbose headers.
  465.  
  466.      C    Cancel the article.  You must be the author to be able to cancel the
  467.           article.
  468.  
  469.      z    Supersede the article.  You must be the author to be able to
  470.           supersede the article.
  471.  
  472.      =    Return to the article selection level.
  473.  
  474.      !    Run command shell.  Type "exit" to return to Yarn.
  475.  
  476.      Esc  Return to the newsgroup selection level.
  477.  
  478. READ MAIL
  479.  
  480.      To read mail, press [Alt-M] at the newsgroup selection level.  This brings
  481.      up a list of mail messages you received.  If you have no mail, you are
  482.      given the opportunity to send mail.
  483.  
  484.      Press [Alt-F] at the newsgroup selection level to bring up a list of
  485.      folders.  You can select a folder to read from this list.
  486.  
  487.      If you start yarn with the -m option, you go directly to reading your
  488.      received mail and skip reading news.  If you start yarn with the -f
  489.      option, you go directly to the folder list and skip reading news.
  490.  
  491. EDIT REPLIES
  492.  
  493.      The Yarn reader allows you to edit the messages in the reply packet.  At
  494.      the newsgroup selection level, press [Alt-R] to display a list of folders
  495.      in the reply packet.  The reply packet may contain up to two folders,
  496.      ``mail'' which holds outgoing mail messages, and ``news'' which holds
  497.      outgoing USENET articles.
  498.  
  499.      By selecting a folder, you go to the message selection level, where the
  500.      program lists the messages in the folder.  Press the [Del] key to delete
  501.      the currently highlighted message.  Press [Alt-E] to edit the message.
  502.  
  503.      To view a message, select it from the message selection level.  While a
  504.      message is displayed, pressing the 'd' key deletes the message.  Press the
  505.      'e' key to edit the message.
  506.  
  507. QUESTIONS AND ANSWERS
  508.  
  509.      ``How do I create SOUP files on my UNIX host?''
  510.  
  511.           The uqwk program creates and processes SOUP files on your UNIX host.
  512.           It is available by anonymous FTP from ftp.gte.com in the /pub/uqwk
  513.           directory.
  514.  
  515.  
  516.  
  517.  
  518.  
  519.                                  Version 0.53                                 8
  520.  
  521.  
  522.  
  523. YARN(1)                                                                 YARN(1)
  524.  
  525.  
  526.           To create a SOUP download packet, named "down.zip" in this example,
  527.           run these commands on your UNIX host:
  528.  
  529.                uqwk +n +L
  530.                zip down.zip AREAS *.MSG
  531.  
  532.           Download the down.zip file to your PC.  Run this command on your PC
  533.           to insert the messages into the Yarn news base:
  534.  
  535.                import down.zip
  536.  
  537.           When you send mail or post articles, the Yarn reader creates a SOUP
  538.           reply packet, named "up.zip" in this example.  Upload the up.zip file
  539.           to your UNIX host.  Run these commands on your UNIX host to send the
  540.           messages in the reply packet:
  541.  
  542.                unzip -U up.zip
  543.                uqwk -m -n +L -RREPLIES
  544.  
  545.  
  546.      ``Sometimes when I select a newsgroup by pressing the space bar from the
  547.      newsgroup selection level, yarn lists less articles than the number of
  548.      unread articles shown.''
  549.  
  550.           This occurs if the newsgroup you selected contains cross-posted
  551.           articles that you already read in another newsgroup.  The program
  552.           marks these articles as read and updates the count of unread articles
  553.           when you select the newsgroup.
  554.  
  555.      ``After running expire, I reduced the keep days for a newsgroup and ran
  556.      expire again, but it didn't delete any more articles.''
  557.  
  558.           Each article is assigned an expiry date after which it is deleted.
  559.           The expire program deletes articles having an expiry date older than
  560.           the current date.  The article storage scheme requires that an
  561.           article's expiry date be set when the article is imported into the
  562.           news base.  Once imported, the article's expiry date cannot be
  563.           changed.  When you change the keep days for a newsgroup, you only
  564.           change how long you keep articles that are subsequently imported.
  565.           You don't affect the expiry dates of articles already in the news
  566.           base.
  567.  
  568.      ``What is the junk newsgroup?''
  569.  
  570.           When the import program encounters an article that doesn't belong to
  571.           any of the groups in the active newsgroup list, it tosses the article
  572.           into the junk newsgroup.  This usually shouldn't happen with properly
  573.           configured software.
  574.  
  575. FILES
  576.  
  577.      <home>\MAIL             Folder directory
  578.      <home>\NEWS             Default save directory
  579.      <home>\REPLIES          Reply work directory
  580.      <home>\YARN             User configuration directory
  581.      <home>\YARN\ALIASES     Mail aliases file
  582.  
  583.  
  584.                                  Version 0.53                                 9
  585.  
  586.  
  587.  
  588. YARN(1)                                                                 YARN(1)
  589.  
  590.  
  591.      <home>\YARN\CONFIG      User configuration file
  592.      <home>\YARN\NEWSRC      Newsgroup subscription file
  593.      <home>\YARN\READART.*   Read cross-posted article lookup table
  594.  
  595.      <yarn>\ACTIVE           Active newsgroup file
  596.      <yarn>\HISTORY.*        Article history lookup table
  597.      <yarn>\INDEX            Article index directory
  598.      <yarn>\NEWS             Article file directory
  599.  
  600.                                ACKNOWLEDGEMENTS
  601.  
  602.      This product uses the SPAWNO routines by Ralf Brown to minimize memory use
  603.      while shelling to DOS and running other programs.
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.                                 Version 0.53                                 10
  650.  
  651.